home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / AIAT 1.0.1 / Headers / Storage / IAStorable.h < prev    next >
Encoding:
Text File  |  1997-09-11  |  5.1 KB  |  133 lines  |  [TEXT/CWIE]
  1. // IAStorable.h -- Some base classes for objects that may reside in a IAStorage.
  2. //    Copyright:    © 1994 - 1996 by Apple Computer, Inc., all rights reserved.
  3.  
  4.  
  5. #pragma once
  6. #ifndef IAStorable_h
  7. #define IAStorable_h
  8.  
  9. #pragma import on
  10.  
  11. #include "IAStorage.h"
  12.  
  13. #pragma IA_BEGIN_EXPORTS
  14.  
  15. // the base class for storable objects
  16. class IAStorable : public IAObject {
  17. public:
  18.     IA_INLINE            ~IAStorable() IA_INLINE_DEF()                // no-op dtor def
  19.     // returns a copy of an object & any memory it points to
  20.     virtual IAStorable*    DeepCopy() const = 0;
  21.     // returns the number of bytes in an objects serialization
  22.     virtual IABlockSize    StoreSize() const = 0;
  23.     // serializes the object to output, writing StoreSize() bytes to output
  24.     virtual void        Store(IAOutputBlock* output) const = 0;
  25.     // deserializes and returns a new object -- reading StoreSize() bytes from input
  26.     virtual IAStorable*    Restore(IAInputBlock* input) const = 0;
  27. protected:
  28.     // methods to simplify subclassing
  29.     // these are called on a new instance to fill in its slots
  30.     virtual void        DeepCopying(const IAStorable* source);                    // no-op impl
  31.     virtual void        Restoring(IAInputBlock* input, const IAStorable* proto);// no-op impl
  32. };
  33.  
  34. /*
  35.  
  36. /// implementations of DeepCopy() and Restore() should work as follows:
  37.  
  38. IAStorable* SubClass::DeepCopy() const {
  39.     SubClass* sub = new SubClass;                // allocate instance
  40.     sub->DeepCopying(this);                        // copy slots
  41.     return sub;                                    // return it
  42. }
  43. void SubClass::DeepCopying(const IAStorable* source) {
  44.     SuperClass::DeepCopying(source);            // copy super slots
  45.     // ... copy subclass slots from source ...
  46. }
  47. */
  48.  
  49. // a subclass for IAStorable's which may be sorted
  50. class IAOrderedStorable : public IAStorable {
  51. public:
  52.     IA_INLINE            ~IAOrderedStorable() IA_INLINE_DEF()    // no-op dtor definition
  53.     // returns true iff and object belongs before neighbor 
  54.     virtual bool        LessThan(const IAOrderedStorable* neighbor) const = 0;
  55.     // returns true iff an object is equal to neighbor
  56.     virtual bool        Equal(const IAOrderedStorable* neighbor) const = 0;
  57. };
  58.  
  59.  
  60. // IAOrderedStorableSet: a sorted set of IAOrderedStorable's
  61.  
  62. class IAOrderedStorableIterator : public IAObject {
  63. public:
  64.     IA_INLINE            ~IAOrderedStorableIterator() IA_INLINE_DEF()// no-op dtor def
  65.     // Advances the iterator to the next entry in the set and returns it.
  66.     // Returns NULL at the end of the set.
  67.     // Note: this returns a DeepCopy() of the object.  Clients must delete.
  68.     virtual IAOrderedStorable*    Next() = 0;
  69. };
  70.  
  71. // When cloneStoreStream set true, OrderedStorableSets will use cloned StoreStreams.  false by default.
  72.  
  73. extern     bool     IACloneOSSetStoreStreams;
  74.  
  75. class IAOrderedStorableSet : public IAObject {
  76. public:
  77.     IA_INLINE                ~IAOrderedStorableSet() IA_INLINE_DEF()// no-op dtor def
  78.     // initializes a new, empty IAOrderedStorable rooted at the named block, leaving it open.
  79.     // a cloned IAStoreStream may be requested to improve threaded throughput
  80.     virtual void            Initialize(IAStorage* storage, IABlockID block,
  81.                                        bool cloneStoreStream = IACloneOSSetStoreStreams) = 0;
  82.     // flushes any cached changes to disk -- should be called before Commit()
  83.     virtual void            Flush() = 0;
  84.     // purges any cached data from memory
  85.     virtual void            Purge() = 0;
  86.     // opens an existing IAOrderedStorable rooted at the named block
  87.     // a cloned IAStoreStream may be requested to improve threaded throughput
  88.     virtual void            Open(IAStorage* storage, IABlockID block,
  89.                                  bool writable = true,
  90.                                  bool cloneStoreStream = IACloneOSSetStoreStreams) = 0;
  91.     // frees all storage associated with the set
  92.     virtual void            Destroy() = 0;
  93.  
  94.     // puts an object into the set, replacing any there.  object is destroyed. 
  95.     virtual bool            Put(IAOrderedStorable* obj) = 0;
  96.     // gets an objects from the set, if any such exists, returning a DeepCopy().
  97.     virtual IAOrderedStorable* Get(const IAOrderedStorable* key) = 0;
  98.     // removes an object from the set, if any
  99.     virtual bool            Remove(const IAOrderedStorable* key) = 0;
  100.  
  101.     // returns the number of entries in the set
  102.     virtual uint32            Count() = 0;
  103.     // returns the total number of bytes of storage allocated by the set
  104.     virtual uint32            TotalSize() = 0;
  105.  
  106.     // creates an iterator positioned before the first element
  107.     virtual IAOrderedStorableIterator*        MakeIterator() = 0;
  108.     // creates an iterator positioned at or after the named element
  109.     virtual IAOrderedStorableIterator*        MakeIterator(const IAOrderedStorable* key) = 0;
  110.  
  111.     // returns an estimate of the fraction of the set which lies before the named key.
  112.     // this is useful (with TotalSize()) for estimating the cost of range iteration.
  113.     virtual float            PositionEstimate(const IAOrderedStorable* key) = 0;
  114.  
  115.     // in the debug libraries, prints some info about the set to the standard output
  116.     virtual void            ReportStats();
  117.     // Get the lock or mutex for committing the entire storage as one transaction
  118.     virtual    IAMutex*        GetMutex() = 0;
  119. };
  120.  
  121. IAExceptionCode                    OrderedStorableSetEntryTooBig = 'VSBE';
  122.  
  123. // Returns an instance of the default implementation of IAOrderedStorableSet -- a B-Tree.
  124. // 'proto' is used to call Restore().  It is deleted when the set is deleted.
  125. IAOrderedStorableSet*        IAMakeOrderedStorableSet(IAOrderedStorable* proto);
  126.  
  127. extern uint32 OrderedStorableSetType;
  128.  
  129. #pragma IA_END_EXPORTS
  130.  
  131. #pragma import reset
  132. #endif
  133.